Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Install tbdocs for the @web5/api package #251

Merged
merged 6 commits into from
Nov 3, 2023
Merged

Install tbdocs for the @web5/api package #251

merged 6 commits into from
Nov 3, 2023

Conversation

leordev
Copy link
Contributor

@leordev leordev commented Oct 31, 2023 •
edited
Loading

  • Installs tbdocs on @web5/api, which will start to bring up doc errors on PRs (powered by api-extractor), see below
  • These errors are non blocking, you can feel free to ignore them if you want to, although not encouraged
  • Since we aligned on this, I'm helping to fix the initial warnings pointed by tbdocs by fixing and adding missing docs (just a first pass, but please review my docs to see if it makes sense!)
    • I tagged everything as @beta but can you please point me to apis that are more stable that we should tag as @public, so that we don't break our customers? (Release tags reference)

Fix #250

@codesandbox CodeSandbox
Copy link

codesandbox bot commented Oct 31, 2023

Review or Edit in CodeSandbox

Open the branch in Web Editor • VS Code • Insiders

Open Preview

leordev
leordev commented Oct 31, 2023
View reviewed changes
packages/api/src/index.ts
Comment on lines +32 to +33
export { utils };
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Required workaround needed by api-extractor.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@leordev Is this limitation with api-extractor something that is planned to be resolved? Seems unfortunate that we have to modify the source code to satisfy api-extractor being unable to understand valid ES2020 syntax.

@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Oct 31, 2023 •
edited
Loading

TBDocs Report

🛑 Errors: 0
⚠️ Warnings: 23

@web5/api

  • Project entry file: packages/api/src/index.ts
📄 File: node_modules/abstract-level/types/abstract-level.d.ts
⚠️ compiler:TS2304: Cannot find name 'this'. #L143
⚠️ compiler:TS2304: Cannot find name 'this'. #L173
⚠️ compiler:TS2304: Cannot find name 'this'. #L187
⚠️ compiler:TS2304: Cannot find name 'this'. #L201
⚠️ compiler:TS2304: Cannot find name 'this'. #L218
📄 File: packages/api/src/did-api.ts
⚠️ extractor:ae-undocumented: Missing documentation for "agent". #L49
⚠️ extractor:ae-undocumented: Missing documentation for "connectedDid". #L50
📄 File: packages/api/src/dwn-api.ts
⚠️ extractor:ae-undocumented: Missing documentation for "agent". #L185
⚠️ extractor:ae-undocumented: Missing documentation for "connectedDid". #L186
📄 File: packages/api/src/protocol.ts
⚠️ extractor:ae-undocumented: Missing documentation for "_agent". #L30
⚠️ extractor:ae-undocumented: Missing documentation for "_metadata". #L31
⚠️ extractor:ae-undocumented: Missing documentation for "_protocolsConfigureMessage". #L32
📄 File: packages/api/src/record.ts
⚠️ extractor:ae-undocumented: Missing documentation for "_agent". #L76
⚠️ extractor:ae-undocumented: Missing documentation for "_attestation". #L77
⚠️ extractor:ae-undocumented: Missing documentation for "_contextId". #L78
⚠️ extractor:ae-undocumented: Missing documentation for "_descriptor". #L79
⚠️ extractor:ae-undocumented: Missing documentation for "_encodedData". #L80
⚠️ extractor:ae-undocumented: Missing documentation for "_encryption". #L81
⚠️ extractor:ae-undocumented: Missing documentation for "_readableStream". #L82
⚠️ extractor:ae-undocumented: Missing documentation for "_recordId". #L83
📄 File: packages/api/src/vc-api.ts
⚠️ extractor:ae-undocumented: Missing documentation for "agent". #L9
⚠️ extractor:ae-undocumented: Missing documentation for "connectedDid". #L10
📄 File: packages/api/src/web5.ts
⚠️ extractor:ae-undocumented: Missing documentation for "connectedDid". #L89

Updated @ 2023-11-03T13:12:15.879Z - Commit: 9b86dcc

@codecov Codecov
Copy link

codecov bot commented Oct 31, 2023 •
edited
Loading

Codecov Report

Merging #251 (8b8fd8a) into main (d442b66) will increase coverage by 0.15%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##             main     #251      +/-   ##
==========================================
+ Coverage   90.95%   91.10%   +0.15%     
==========================================
  Files          69       69              
  Lines       13317    13549     +232     
  Branches     1340     1340              
==========================================
+ Hits        12112    12344     +232     
  Misses       1180     1180              
  Partials       25       25
Components Coverage Δ
api 95.30% <100.00%> (+0.96%) ⬆️
common 95.00% <ø> (ø)
credentials 92.77% <ø> (ø)
crypto 100.00% <ø> (ø)
dids 91.58% <ø> (ø)
agent 88.16% <ø> (ø)
identity-agent 59.05% <ø> (ø)
proxy-agent 58.59% <ø> (ø)
user-agent 57.36% <ø> (ø)

@leordev leordev changed the title Leordev/tbdocs api Install tbdocs for the @web5/api package Oct 31, 2023
@leordev
Copy link
Contributor Author

leordev commented Oct 31, 2023

TBDocs Report

🛑 Errors: 0 ⚠️ Warnings: 23

The above warnings will be fixed at the tbdocs level repo (hence could be ignored)

  • The abstract-level compilations errors should be suppressed
  • The missing documentation attributes are all from private properties that will be fixed with this api-extractor PR (I just need to test their changes and make sure it worked!)

@leordev leordev marked this pull request as ready for review October 31, 2023 17:30
frankhinek
frankhinek suggested changes Nov 3, 2023
View reviewed changes
Copy link
Contributor

@frankhinek frankhinek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@leordev Thanks for getting this work started and contributing all of the much needed comments! 😄

packages/api/src/record.ts Outdated Show resolved Hide resolved
packages/api/src/did-api.ts Outdated Show resolved Hide resolved
packages/api/src/dwn-api.ts Outdated Show resolved Hide resolved
packages/api/src/dwn-api.ts Outdated Show resolved Hide resolved
@frankhinek
Copy link
Contributor

@leordev Can you also rebase on main to clear the security-audit check failure? The package-lock.json in main already has the patched version of browserify-sign updated. Thanks.

@leordev leordev force-pushed the leordev/tbdocs-api branch from 6d3c72b to 63a5616 Compare November 3, 2023 13:04
@leordev leordev requested a review from frankhinek November 3, 2023 13:09
@leordev
Copy link
Contributor Author

leordev commented Nov 3, 2023

Thank you @frankhinek ! Just rebased and implemented the suggestions.

Did you check if all the interfaces that I tagged as @beta but should already be in a stable enough state to be considered @public?

If all of them should be @beta, feel free to go ahead and merge!

@frankhinek
Copy link
Contributor

Thank you @frankhinek ! Just rebased and implemented the suggestions.

Thanks! 👍

Did you check if all the interfaces that I tagged as @beta but should already be in a stable enough state to be considered @public?

If all of them should be @beta, feel free to go ahead and merge!

I think @beta is fine for now. We've got some changes upcoming to re-align the Web5 SDKs implemented in TS, Kotlin, and Swift/Rust so that might introduce changes.

frankhinek
frankhinek approved these changes Nov 3, 2023
View reviewed changes
Copy link
Contributor

@frankhinek frankhinek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! 🚀 Let's ship it!

@frankhinek frankhinek merged commit 1754dd6 into main Nov 3, 2023
23 of 24 checks passed
@frankhinek frankhinek deleted the leordev/tbdocs-api branch November 3, 2023 13:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@frankhinek frankhinek frankhinek approved these changes

@csuwildcat csuwildcat Awaiting requested review from csuwildcat csuwildcat is a code owner

@mistermoe mistermoe Awaiting requested review from mistermoe

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Install tbdocs on @web5/api and do a first pass on the docs
2 participants
@leordev @frankhinek